13 Using OPXs on THE Series 5 


The Series 5 uses language extensions provided in separate DLLs written specially for 
OPL support. These DLLs have the file extension OPX. 


It is not within the scope of this manual to cover how to develop OPXs yourself, as it 
requires knowledge of the C++ language. If you require details of how to do this, you 
should obtain a copy of the EPOC32 C++ Software Development Kit (SDK) from Psion 
Software ple. 


OPX procedures for handling the following are provided in the ROM: 
e Date / time extras 

System controls 

Bitmaps 

Sprites 


Database extras 


e Printing 
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OPX Overview 


A maximum of 255 OPXs can be used in any one OPL module and any OPX may have up to 65535 
procedures defined in it. If these values are exceeded then errors are reported at translate-time (see the 
‘Error Handling’ chapter). 


OPX HEADER FILES 
The OPX supplier provides an OXH header file. This provides the declaration for the OPX, specifying 
its name UID and version number (see below), followed by its procedure prototypes. 


The new INCLUDE keyword is used to include these header files. Alternatively, the declaration can be 
inserted directly into the OPL file, i.e. 














DECLARE OPX <opxName>, <uid>,<version> 
<protoTypel> : <ordinall> 


<protoType2> : <ordinal2> 








END DECLARE 











where, 


<name> is the name of the OPX without the .OPX extension. The OPX is stored ina 
\System\Opx\ folder on any drive, with the drives scanned from Y: to A: and then Z: ifno path is 
specified. This allows ROM OPXs (in Z: ) to be overridden if required. 


<uid> is the UID of the OPX. The specification of a UID as well as a name guards against OPXs 
being with the same name being confused, which could otherwise cause serious problems. The UID is 
checked on loading the OPX and a ‘Not supported’ error will result if the UIDs in the header file and in 
the OPX itself do not match. 


<version> is the version number of the OPX. The version number of an OPX will be increased 
when any new procedures are added. OPL will refuse to load an OPX which reports that it can’t 
support the version number given in the declaration. The version number expressed in hex is e.g. $0100 
to represent version 1.00, $0102 for version 1.02 etc. In general, an OPX supplier will increment the 2 
low digits (the so-called minor version number) for backward compatible changes, and will increment 
the 2 high digits for major incompatible changes. 


<prototype> specifies the name, return type and parameters of an OPX procedure in the same way 
as for an OPL procedure when using the EXTERNAL keyword. Numeric parameters to OPX 
procedure can be passed by reference using BYREF. This means that the value of the variable can be 
changed by the OPX procedure. The OPX procedure prototype is followed additionally by a colon and 
then the 


<ordinal> specifies the ordinal number of the procedure in the OPX itself. This is used to call the 
correct procedure, i.e. the OPX is linked by ordinal. 


If an OPX procedure name clashes with one of your OPL procedures, or with that of another OPX 
procedure, you can make a copy of the OXH file and change the name of the offending procedures, but 
not the return type, parameter list or ordinal. You should then include this new OXH file in your 
module and the new name can then be used to refer to the procedure in your code. 


For example, consider the OPX declaration, 





DECLARE OPX XXOpx, XXOpxUid&, XXOpxVersioné& 











XXClose%: (id&) : 1 
ProcWithLongParam: (aLong&) : 2 


AddOneToParams: (BYREF parl%,BYREF par2&, BYREF par3) : 3 























END DECLARE 
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If a short integer is passed to ProcWithLongParam:, the translator will automatically convert it to 
a long integer. 


The AddOneToParams: procedure adds one to each of the parameters. This is possible because the 
parameters are passed by reference using BYREF. Parameters passed by reference must be variables 
rather than constant values because the OPX will write back to the variable. The variable type must 
always be the same as given in the declaration. 


CALLBACKS FROM OPX PROCEDURES 


An OPX procedure can call back to a module procedure. This is often useful if the OPX needs some 
information that is not known when the OPX procedure is initially called, or if it requires a large 
amount of data which needs to be sent piecemeal. 


The OPX provider will specify the exact form of the procedure which you must provide. 


OPXs INCLUDED IN THE SERIES 5 
Procedures for handling the following are provided in the ROM: 


e Date / time extras 


e System - a variety of procedures for system control, e.g. backlight control, sound control, file 
and application control, etc. 


e Bitmaps - for use with buttons and Sprites. 
e Sprites 
e Database extras 


These OPXs and their OXHs have default paths in the ROM (Z:), but the full path for any OPX may 
be supplied. These are \System\Op1\ for the header files and \System\Opx\ for the OPXs 
themselves. The OPX header files are stored in the ROM, but may be created in RAM by using the 
‘Create standard files’ option in the ‘Tools’ menu in the Program editor. 


With these OPXs, the OPL programmer is sometimes given direct access to objects via pointers (for 
efficiency). Otherwise sprites, for example, could not be set up using an array of IDs. These objects can 
be explicitly deleted to free memory or else they will be deleted when the program exits 


Date OPX 


To use this OPX, you must included the header file Date.oxh, which contains the following declaration: 

















DECLARE OPX DATE, KUidOpxDate&, KOpxDateVersions 





DTNewDateTimeé: (year&,monthé,dayé, hour&,minuteé&,secondé&,microé) : 1 


DTDeleteDateTime: (id&) : 2 





DTYear&: (id&) : 3 
DTMonth&: (idé&) : 4 
DTDay&: (id&) : 5 
DTHour&: (id&) : 6 
DTMinute&: (id&) : 7 


DTSecond&: (id&) : 8 








DTMicroé&: (id&) : 9 
DTSetYear: (id&,yearé&) : 10 
DTSetMonth: (id&,monthé) : 11 


DTSetDay: (idé&,dayé&) : 12 





DTSetHour: (id&,houré) : 13 
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DTSetMinute: (id&,minuteé) : 14 


DTSetSecond: (id&,secondé) : 15 
DTSetMicro: (id&,micro&) : 16 
DTNow&: : 17 

















DTDateTimeDiff: (starté&,end&,BYREF year&,BYREF month&, BYREF 
dayé&,BYREF houré,BYREF minuteé,BYREF secondé,BYR 
microé) : 18 














fl 
i) 


DTYearsDiffé: (starté&,end&) : 19 
DTMonthsDiff&: (starté&,end&) : 20 
DTDaysDiff&: (start&,end&) : 21 

DTHoursDiffé: (starté&,end&) : 22 


DTMinutesDiffé: (starté&,end&) : 23 





DTSecsDiff&: (starté&,end&) : 24 





DTMicrosDiffé&: (starté&,end&) : 25 





DTWeekNoInYear&: (id&, yearstart&,rule&) : 26 
DTDayNoInYearé: (id&, yearstart&) : 27 


DTDayNoInWeeké: (id&) : 28 





DTDaysInMonthé: (id&) : 29 





DTSetHomeTime: (id&) : 30 
LCCountryCode&: : 31 
LCDecimalSeparatorS: : 32 
LCSetClockFormat: (format&) : 33 
LCClockFormat&: : 34 
LCStartOfWeek&: : 35 


LCThousandsSeparatorS: : 36 











END DECLARE 











DTNEWDATETIME8&: 


Usage: 
1d&=DTNEWDATETIMES&: (year&,monthé&, day&, hour&,minute&, second&,microé&) 

















Creates a new date/time object which contains all the supplied date/time components and returns a 
handle idé for it. 


The year is stored as the usual four figure year, e.g. 1997. 

The month is stored as | for January, 2 for February, etc. 

The day is stored as the day number in the month. 

The hour is the hour of the day in 12 or 24 hour clock according to the system setting. 


The minutes, seconds and microseconds are stored as the usual values 0 to 59 for minutes and seconds 
and 0 to 999 for microseconds. 


See DTDELETEDATETIME:. 


DTDELETEDATETIME: 
Usage: DELETEDATETIME: (id&) 
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Deletes the date/time object with handle id&. This should be called when a date/time object is no 
longer needed. Date/time objects will be deleted automatically on unloading the Date OPX or the 
module which uses it. 


See DTINEWDATETIME&:, DTINOW&:. 


DTYEAR&: 
Usage: y&=DTYEARS&: (idé&) 





Returns the year component y& which is stored in the date/time object with handle idé. 
See DINEWDATETIME&:. 

DTMONTH&: 
Usage: m&=DTMONTHS: (idé) 


Returns the month component m& which is stored in the date/time object with handle idé. 


See DTINEWDATETIME&:. 





DTDAY&: 
Usage: day&=DTDAY&: (idé) 


Returns the day component day & which is stored in the date/time object with handle idé. 
See DINEWDATETIME&:. 


DTHOURE&: 
Usage: h&=DTHOURS: (idé&) 


Returns the hour component h& which is stored in the date/time object with handle idé. 


See DTINEWDATETIME&: 


DTMINUTE&: 
Usage: m&=DTMINUTEE: (id&) 





Returns the minutes component mé& which is stored in the date/time object with handle idé. 


See DTINEWDATETIME&:. 


DTSECOND8&: 
Usage: s&=DTSECONDE: (id&) 





Returns the seconds component s & which is stored in the date/time object with handle idé. 
See DINEWDATETIME&:. 

DTMICRO&: 

Usage: m&=DTMICROS&: (idé) 


Returns the microseconds component mé which is stored in the date/time object with handle idé. 


See DTINEWDATETIME&:. 


DTSETYEAR: 
Usage: DISETYEAR: (y&,id&) 














Sets the year component which is stored in the date/time object with handle idé to y&. 


See DTINEWDATETIME&:. 
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DTSETMONTH: 
Usage: DTISETMONTH: (m&, idé&) 





Sets the month component which is stored in the date/time object with handle idé to mé&. 


See DTINEWDATETIME&:. 


DTSETDAY: 
Usage: DISETDAY: (day&, idé) 





Sets the day component which is stored in the date/time object with handle idé& to days. 
See DINEWDATETIME&:. 





DTSETHOUR: 
Usage: DISETHOUR: (h&, id&) 





Sets the hour component which is stored in the date/time object with handle idé& to hé. 


See DTINEWDATETIME&:. 





DTSETMINUTE: 
Usage: DTISETMINUTE: (mé&, idé) 








Sets the minutes component which is stored in the date/time object with handle id& to mé. 


See DINEWDATETIME&:. 


DTSETSECOND: 
Usage: DTISETSECOND: (s&,idé) 














Sets the seconds component which is stored in the date/time object with handle idé& to sé. 


See DTINEWDATETIME&:. 





DTSETMICRO: 
Usage: DTISETMICRO: (m&, idé&) 





Sets the microseconds component which is stored in the date/time object with handle id& to mé. 


See DTINEWDATETIME&:. 





DTNOW8&: 
Usage: id&=DTNOWS: 


Creates a new date/time object which contains all the date/time components of the current time and 
returns a handle idé for it. 


Example: Timing a loop 


start&=DTNowé&: 


WHILE condition 





ENDWH 


end&=DTNowé&: 








PRINT “Time to do loop was”,DTMicrosDiffé&: (starté&,end&) 
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See DTINEWDATETIME&:. 


DTDATETIMEDIFF: 

Usage: DTDATETIMEDIFF: (start&,endé&,BYREF yearé&,BYREF monthé,BYREF 
dayé&,BYREF houré,BYREF minuteé, BYREF 
secondé&,BYREF microé) 



































Calculates the exact difference between two date/time objects with handles start & and end& in the 
form of a date/time object. The difference is returned in the variables yearé, monthé etc. 


DTYEARSDIFF&: 
Usage: dif f&=DTYEARSDIFFé: (starté&, endé) 





Returns the difference dif fé& in whole years between the two date/time objects with handles start & 
and end&. 


See DTINEWDATETIME&:. 


DTMONTHSDIFF&: 
Usage: dif f&=DTMONTHSDIFFS&: (starté, end&) 


Returns the difference dif f& in whole months between the two date/time objects with handles 
starté& and endé. 


See DINEWDATETIME&:. 


DTDAYSDIFF&: 
Usage: dif f&=DTDAYSDIFF&: (start&,endé&) 


Returns the difference di ff & in whole days between the two date/time objects with handles start & 
and endé. 


See DTINEWDATETIME&:. 


DTHOURSDIFF&: 
Usage: dif f&=DTHOURSDIFF&: (starté&, endé&) 


Returns the difference dif fé& in whole hours between the two date/time objects with handles start & 
and end&. 


See DTINEWDATETIME&:. 


DTMINUTESDIFF&: 
Usage: dif f&=DTMINUTESDIFFS&: (starté,endé&) 





Returns the difference dif fé& in whole minutes between the two date/time objects with handles 
starté& and endé. 


See DTINEWDATETIME&:. 


DTSECONDSDIFF&: 
Usage: dif f£&=DTSECONDSDIFF&: (starté, endé&) 





Returns the difference dif fé& in whole seconds between the two date/time objects with handles 
starté& and endé. 


See DTINEWDATETIME&:. 


DTMICROSDIFF&: 
Usage: dif f£&=DTMICROSDIFFS&: (start&,end&) 
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Returns the difference dif f£é& in whole microseconds between the two date/time objects with handles 
starté& and endé. 


See DINEWDATETIME&:, DTINOW&:. 


DTWEEKNOINYEAR8&: 
Usage: w&=DTWEEKNOINYEARE: (id&, yearstarté, ruleé) 

















Returns the week number in the year of the date/time object with handle id&. The first day of the year 
is specified by the date/time object with handle yearstart&. This would usually be set to 1 January 
in the appropriate year, but also allows you to set the star of the year to the beginning of the financial 
year or the academic year, for example. 


ruleé can take three values (0,1,2), allowing the week number to be calculated by one of three 
different rules: 


value meaning 


0 the first day of the year is always in week one, 
1 requires the first week of the year to have at least four days in it, 
2 requires the first week of the year to have the full seven days. 


The Agenda application and other Series 5 applications use the rule with value | by default. 


DTDAYNOINYEAR&: 
Usage: DTDAYNOINYEARE: (id&, yearstarté) 





Returns the day number in the year of the date/time object with handle id&. The first day of the year is 
specified by the date/time object with handle yearstarté. 


DTDAYNOINWEEK8&: 
Usage: n&é=DTDAYNOINWEEKE: (id&) 














Returns the day number in the week (1-7) of the date/time object with handle idé. 


DTDAYSINMONTH8&: 
Usage: n&=DTDAYSINMONTHS: (idé) 


Returns the number of days in the month of the month specified by the month component of the 
date/time object with handle idé. 


DTSETHOMETIME: 
Usage: DISETHOMETIME: (idé&) 

















Sets the system time to the time specified in the date/time object with handle idé. 


LCCOUNTRYCODE&: 
Usage: cc&=LCCOUNTRYCODE&: 





Returns the country code for the current system home country (LC stands for ‘Locale’), which may be 
used to select country-specific data. The country code for any given country is the international 
dialling prefix for that country 


LCDECIMALSEPARATORS: 
Usage: decSepS=LCDECIMALSEPARATORS : 











Returns the decimal separator (the character used in decimal numbers to separate whole part from 
fractional part) according to the local system setting. 
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LCSETCLOCKFORMAT: 
Usage: LCSETCLOCKFORMAT: (formaté) 





Sets the system clock format to either digital or analog. If format &=0 then the clock is set to analog 
or if it is 1 then the clock is set to digital. 


LCCLOCKFORMAT8&: 
Usage: format &=LCCLOCKFORMATE&: 
Returns the current system clock format The procedure returns 0 if the system clock is analog and | if 


it is digital. 


LCSTARTOFWEEK&: 
Usage: start &=LCSTARTOFWEEK&: 














Returns the day of the week which set as the first day of the week in the system setting. A return value 
of | indicates Monday, 2 Tuesday, and so on. 


LCTHOUSANDSSEPARATORS: 
Usage: thouSep$=LCTHOUSANDSSEPARATORS : 





Returns the thousands separator (the character used to separate every three digits of a large number) 
according to the local system setting. 


System OPX 


To use this OPX, you must included the header file System.oxh, which contains the following 
declaration: 





DECLARE OPX SYSTEM, KUidOpxSystemé&, KOpxSystemVersion% 














BackLightOn&: : 1 





SetBackLightOn: (state&é) : 2 





SetBackLightOnTime: (secondsé) : 3 





SetBacklightBehavior: (behaviour&) : 4 


IsBacklightPresent&: : 5 





SetAutoSwitchOffBehavior: (behaviour&) : 6 


SetAutoSwitchOffTime: (seconds&) : 7 





SetActive: (state&) : 8 
ResetAutoSwitchOffTimer: : 9 
SwitchoOff: : 10 


SetSoundEnabled: (state&) : 11 





SetSoundDriverEnabled: (state&) : 12 


SetKeyClickEnabled: (stateé&) : 13 














SetPointerClickEnabled: (state&) : 14 
SetDisplayContrast: (valueé) : 15 
MaxDisplayContrast&: : 16 
TsReadOnlyé: (file$) : 17 





IsHidden&: (fileS) : 18 
IsSystemé&: (fileS) : 19 
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SetReadOnly: (fileS,stateé&) : 20 





SetHiddenFile: (file$,state&) : 21 





SetSystemFile: (fileS,state&) : 22 





VolumeSize&: (drive&) : 23 


VolumeSpaceFree&: (drive&) : 24 








VolumeUniquelDé&: (driveé&) : 25 
MediaTypeé&: (drive&) : 26 


GetFileTime: (fileS,DateTimeId&) : 27 








SetFileTime: (file$,DateTimeId&) : 28 
DisplayTaskList: : 29 


SetComputeMode: (State&) : 30 





RunAppé: (libS,doc$,tail$,cmd&) : 31 





RunExe&: (names) : 32 





LogonToThread: (threadidé&,BYREF statusWord&) : 33 





TerminateCurrentProcess: (reason&) : 34 
TerminateProcess: (proc$,reasoné&) : 35 
KillCurrentProcess: (reason&) : 36 
KillProcess: (proc$,reason&) : 37 
PlaySound: (file$,volume&) : 38 


PlaySoundA: (file$,volumeé,BYREF statusWordé&) : 39 








StopSound&: : 40 

Modé: (left&,right&) : 41 
XOR&: (left&,righté&) : 42 
LoadRscé: (fileS) : 43 
UnLoadRsc: (id&) : 44 
ReadRsc$: (id&) : 45 


ReadRscLong&: (id&) : 46 





CheckUid$: (Uid1l&,Uid2&,Uid3&) : 47 





SetPointerGrabOn: (WinId&,state&) : 48 
MachineName$: : 49 


MachineUniqueld: (BYREF high&,BYREF low&) : 50 








EndTaské: (threadId&,previousé&) aa owl 











KillTask&: (threadId&,previous&) : 52 





GetThreadIdFromOpenDocé&: (doc$,BYREF previous&) : 53 





GetThreadIdFromAppUidé: (uidé&,BYREF previous&) : 54 
SetForeground: : 55 


SetBackground: : 56 








SetForegroundByThread&: (threadId&,previous&) : 57 
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SetBackgroundByThread&: (threadIdé&,previous&) : 58 





GetNextWindowGroupNameS: (threadId&,BYREF previous&) : 59 


GetNextWindowld&: (threadId&,previousé&) : 60 





SendKeyEventToApps&: (threadiId&, previousé, code&, scanCodeé&, 
modifiers&,repeatsé&) : 61 


IrDAConnectToSendé&: (protocolS,porté) : 62 





IrDAConnectToReceive: (protocol$,port&,BYREF statusW&) : 63 





H 
ry 


DAWrite: (chunk$,BYREF statusW&) : 64 
IrDARead$: : 65 


IrDAReadA: (stringAddré&,BYREF statusW&): 66 








IrDAWaitForDisconnect: : 67 





IrDADisconnect: : 68 
MainBatteryStatus&: :69 


BackupBatteryStatus&: :70 








CaptureKeyé: (keyCode&,mask&,modifieré&) :71 


CancelCaptureKey: (handle&) :72 





SetPointerCapture: (winId&,flags&) :73 








ClaimPointerGrab: (winId&,stateé&) :74 





OpenFileDialogS: (seedFile$,uidl&,uid2&é,uid3&) : 75 
CreateFileDialog$: (seedPath$) : 76 
SaveAsFileDialogS$: (seedPath$,BYREF useNewFile%) : 77 

















END DECLARE 





BACKLIGHTON&: 
Usage: backLight &=BACKLIGHTONE: 


Returns -1 if the backlight is switched on or 0 if it is switched off. 


SETBACKLIGHTON: 
Usage: SETBACKLIGHTON: (state&) 





Switches the backlight on if state&=1 or off if state&=0. 


SETBACKLIGHTONTIME: 
Usage: SETBACKLIGHTONTIME: (seconds &) 








Sets the time in seconds (Seconds &) that the backlight should remain on after it has been switched 
on. 


SETBACKLIGHTBEHAVIOR: 
Usage: SETBACKLIGHTBEHAVIOR: (behavioré) 











Sets the backlight’s turning off behaviour. 
behavior &=0 sets the turning off of the backlight to be on a timer, 


behavior&=1 sets the backlight not to be on a timer. 
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ISBACKLIGHTPRESENT&: 
Usage: ret &=ISBACKLIGHTPRESENTS&: 














Returns -1 if there is a backlight present and 0 if there is not. 


SETAUTOSWITCHOFFBEHAVIOR: 
Usage: SETAUTOSWITCHOFFBEHAVIOR: (behavior&) 








Sets the machine’s auto switch off behaviour. 
behavior&=0 disables the machine’s auto switch off mechanism. 
behavioré=1 sets the machine auto switch off to occur only when its batteries are low. 


behavioré=2 sets the machines auto switch off to occur always. 


SETAUTOSWITCHOFFTIME: 
Usage: SETAUTOSWITCHOFFTIME: (seconds&) 








Sets the time in seconds (seconds &) for which the machine may remain switched on when it is not 
being used. 


SETACTIVE: 
Usage: SETACTIVE: (stateé&) 








Sets the current process active if state &=1 or not active if state&=0. This will determine whether 
or not the machine can automatically turn off when the user is not using the machine: if the process is 
active then the machine will not automatically turn off. 


RESETAUTOSWITCHOFFTIMER: 
Usage: RESETAUTOSWITCHOFFTIMER: (seconds&) 

















‘Tickles’ the machine’s auto switch off timer, restarting its count down to switching off. 
SWITCHOFF: 
Usage: SWITCHOFF: 


Switches off the machine. 


A As with the keyword OFF, you should be careful not to use SWITCHOFF: in a loop. If you do, it 
may be impossible to switch the Series 5 back on, and you may then have to reset it. 


SETSOUNDENABLED: 
Usage: SETSOUNDENABLED: (stateé) 

















Enables the machine’s sound if state &=1 or disables it if state &=0. 


SETSOUNDDRIVERENABLED: 
Usage: SETSOUNDDRIVERENABLED: (stateé&) 




















Switches the machines sound driver on if stateé=1 or offif state&=0. 


SETKEYCLICKENABLED: 
Usage: SETKEYCLICKENABLED: (state&) 


























Determines whether or not a keypress makes a click. state&=1 enables the click and state &=0 
disables it. 


SETPOINTERCLICKENABLED: 
Usage: SETPOINTERCLICKENABLED: (state&) 
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Determines whether or not a pointer event makes a click. (A pointer event occurs whenever the 
machine’s screen is pressed.) state &=1 enables the click and state&=0 disables it. 


SETDISPLAYCONTRAST: 
Usage: SETDISPLAYCONTRAST: (valueé) 





Sets the contrast on the machine’s screen. value& specifies the contrast value, which can be between 
zero and the maximum display contrast. 


See MAXDISPLAYCONTRAST&:. 


MAXDISPLAYCONTRAST&: 
Usage: maxContrast &=MAXDISPLAYCONTRASTE&: 


Returns the maximum value to which the machines display contrast can be set. 


See SETDISPLAYCONTRAST.:. 


ISREADONLY8&: 
Usage: readOnly&=ISREADONLY«&: (fileS) 








Returns -1 if the file, £ileS, is a read-only file and 0 if it is not. 


ISHIDDEN&: 
Usage: hidden&=ISHIDDEN&: (fileS) 





Returns -1 if the file, £ile$, is hidden by the system and 0 if it is not. 


ISSYTEM&: 
Usage: system&=ISSYTEM&: (files) 





Returns -1 if the file, £ileS, is a system file and 0 if it is not. 


SETREADONLY: 
Usage: SETREADONLY: (file$,stateé&) 














Sets the file, fileS, to be read only if state&=1 or not read-only if state &=0. 


SETHIDDENFILE: 
Usage: SETHIDDENFILE: (file$,state&) 

















Sets the file, fileS, to be hidden by the system if state&=1 or not to be hidden if state &=0. 


SETSYSTEMFILE: 
Usage: SETSYSTEMFILE: (fileS,stateé&) 

















Sets the file, fileS, to be a system file if state&=1 or not to be a system file if state&=0. 


VOLUMESIZE&: 
Usage: VOLUMESIZES&: (driveé) 














Returns the size in bytes of the storage space on the drive specified by driveé. driveé can take 
values 0 to 25. 0 specifies the A:, 1 specifies B:, 2 specifies C: and so on. 


VOLUMESPACEFREE8&: 
Usage: free &=VOLUMES PACEFREES&: (driveé) 




















Returns the size in bytes of the storage space that is available for use on the drive specified by 
driveé. driveé can take values 0 to 25. 0 specifies the A:, 1 specifies B:, 2 specifies C: and so 
on. 
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VOLUMEUNIQUEID&: 
Usage: volUid&=VOLUMEUNIQUEID&: (driveé&) 














Returns the unique identification number of the media on the drive specified by drive&. driveé& 
can take values 0 to 25. 0 specifies the A:, 1 specifies B:, 2 specifies C: and so on. 


See MEDIATYPE&:. 


MEDIATYPE&: 
Usage: media&=MEDIATYPEE&: (driveé&) 








Returns the media type present on the drive specified by driveé&. driveé can take values 0 to 25. 0 
specifies the A:, 1 specifies B:, 2 specifies C: and so on. The value returned may be any of the 
following, 




















value meaning constant declaration in System.oxh 
0 no media present CONST KMediaNotPresent&=0 
1 media unknown CONST KMediaUnknowné=1 
2 floppy disk CONST KMediaFloppy&=2 

3 hard disk CONST KMediaHardDiské=3 
4 CD-ROM CONST KMediaCdRom&=4 

5 RAM CONST KMediaRamé&=5 

6 flash CONST KMediaFlash&é=6 

7 ROM CONST KMediaRomé=7 

8 remote CONST KMediaRemote&=8 
GETFILETIME: 

















Usage: GETFILETIME: (file$,dateTimeldé&) 


Returns the time that the file, £ile$, was last modified into dateTimeId&. It is necessary to pass 
this procedure the ID of a date/time object which the procedure will then set to the required time. To 
obtain and read a date/time object, see the ‘Date OPX’ section. 


SETFILETIME: 
Usage: SETFILETIME: (file$,dateTimeldé&) 

















Sets the time that the file, file$, was last modified to dateTimelIdé&. It is necessary to pass this 
procedure the ID of a date/time object which the procedure will use to set the time. To get a date/time 
object, which provides microsecond accuracy, see the ‘Date OPX’ section. 


DISPLAYTASKLIST: 
Usage: DISPLAYTASKLIST: 
Displays the system-wide task list. The user may then close a file, go to another task or close the 


dialog. 


SETCOMPUTEMODE: 
Usage: SETCOMPUTEMODE: (stateé) 

















Changes the priority control for the current program. 
The following values are available for stateé&: 
value meaning constant declaration in System.oxh 


0 compute mode disabled CONST KComputeModeDisabledé=0 
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iL compute mode onCONST KComputeModeOn&=1 
2 compute mode off CONST KComputeModeOff&=2 


This puts the current process into compute mode (state &=KComputeModeOn§&) or takes it out of 
compute mode (state&=KComputeModeOf f &). In compute mode, a process runs at the lower 
background priority even when it is the foreground process. Disabling compute mode control 
(state&=KComputeModeDisabled&) prevents the window server from changing the program’s 
priority when it moves between background and foreground. 


OPL runs in compute mode by default to support simple OPOs which cannot always be assumed to be 
well-behaved programs. 


This default behaviour is necessary because OPL programs would not otherwise give any background 
programs a chance to run, simply by running in a tight loop. If your program doesn’t run in a tight 
loop, Le. if it calls GETEVENT32, GET, etc. regularly, you can use 

SETCOMPUTEMODE: (KComputeModeOff&). 

















aN Note that TBarInit: in Toolbar.opo sets compute mode off, since any rtp that has a toolbar 
shouldn’t be running in a tight loop at any time. (See the ‘Friendlier Interaction’ chapter for more 
details.) 


RUNAPP8&: 
Usage: thread&=RUNAPP&: (libS,doc$,tail$,cmdé) 


Runs an application and returns a thread ID for the application. The thread ID can be used to logon to 
the application, to find out when and why it finished. This ID can also be used to locate the window 
group, end the task etc. 


libS is the C++ application name. 
doc$ is the document name, if any, to pass to the application. 
tail$ is the tail end, needed only by certain applications such as OPL. 


cmdé& can take values: 


value meaning 

0 open 

1 create 

2 run 

3 background 


The values 0, 1 and 2 are the same as for CMDS (3) (see the ‘Alphabetic Listing’ chapter). The value 3 
will run the application in the background. 


For example, to run an OPL program: 

k&=RUNAPPS&: (“OPL”, *”, “RZ: \System\Opl\Toolbar.opo”, 2) 
Note that tailS contains a leading R: this is required by OPL. 

To open the Data help file: 

k&=RUNAPPS&: (“Data”,“Z:\System\Data\Help”,*”,0) 

See also the ‘OPL Applications’ section in the ‘Advanced Topics’ chapter. 
See LOGONTOTHREAD:. 


RUNEXE&: 
Usage: RUNEXE&: (file$) 














Runs an executable EXE file fileS and returns its thread ID. The thread ID can then be used to logon 
to the thread and find out when and why it finished. 
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See LOGONTOTHREAD:. 


LOGONTOTHREAD: 
Usage: LOGONTOTHREAD: (threadIdé, statusWordé) 





Logs on to the thread with ID threadIdé and sets the status word statusWordé when the thread 
has completed. As for other 32-bit status words, statusWé& will be set to &80000001 for pending and 
0 for successful completion. 


TERMINATECURRENTPROCESS: 
Usage: TERMINATEPROCESS: (reasoné) 

















Terminates the current process giving it the reason reason&. This causes the process to receive a 
shutdown message. reasoné may take any value, with zero used to mean no errors. 


TERMINATEPROCESS: 
Usage: TERMINATEPROCESS: (proc$, reasoné) 

















Terminates the process proc$ giving it the reason reasoné. This causes the process to receive a 
shutdown message. reasoné may take any value, with zero used to mean no errors. 


KILLCURRENTPROCESS: 
Usage: KILLCURRENTPROCESS: (reasoné) 








Kills the current process giving it the reason reasoné. The process is killed without receiving a 
shutdown message. reasoné may take any value, with zero used to mean no errors. 


KILLPROCESS: 
Usage: KILLPROCESS: (procS, reason&) 





Kills the process proc$S giving it the reason reasoné. The process is killed without receiving a 
shutdown message. reasoné may take any value, with zero used to mean no errors. 


PLAYSOUND: 
Usage: PLAYSOUND: (fileS,volumeé) 


Plays the file file$, which may be a sound file or an alarm file. Does not return until the sound has 
completed. 


volumeé specifies the volume at which the file should be played, 0 specifies no volume and 3 
specifies maximum volume. The play will be synchronous (i.e. the OPL program will stop running 
until the file has finished playing). For asynchronous sound playing see PLAYSOUNDA:. 


PLAYSOUNDA: 
Usage: PLAYSOUNDA: (file$,volume&, statusWordé) 


Plays the file file$, which may be a sound file or an alarm file, asynchronously. It returns 
immediately, with the status word being set on completion or cancellation of the sound. 


volumeé specifies the volume at which the file should be played, 0 specifies no volume and 3 
specifies maximum volume. The play will be asynchronous (i.e. the OPL program will continue 
running while the sound file is playing). statusWordé is the variable which will contain 
information about the state of the sounds file play. For synchronous sound playing see PLAYSOUND:. 


STOPSOUND8: 
Usage: STOPSOUNDS&: 


Stops the sound file that is currently playing. The return value is | if there was a sound file playing and 
0 if not. 


See PLAYSOUND:, PLAYSOUNDA.:. 
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MOD8&: 
Usage: rem&=MODé: (lefté&,right&) 


Returns left & modulo right é (i.e. the remainder of left & divided by right &). 


XOR&: 
Usage: res&=XOR&: (lefté&,right&) 


Returns the exclusive OR of left & and rights. A bit in the result has value 1| if the corresponding 
bit is set in either left & or in righté&, but not in both, otherwise it is 0. 


E.g. with Left &=5 (binary 00000101) and right &=3 (binary 00000011), 
XORE&: (left&,right&) returns 6 (binary 00000110). 


left& 00000101 
right& 00000011 
XORE: (lefté&, right&) 00000110 
This is often used to invert particular bits in an integer.So left&=XOR&: (lefté&, 3) inverts bits 0 


and 1 in lefté, where bit 0 is the rightmost bit, and leaves the other bits alone. 


LOADRSC8&: 
Usage: id&=LOADRSC&: (fileS) 


Loads the resource file £i1e$ and returns a handle for it. 


See UNLOADRSC:, READRSC$:. 


UNLOADRSC: 
Usage: UNLOADRSC: (idé&) 


Unloads the resource file whose handle is idé. 


See LOADRSC&:. 


READRSCS$: 
Usage: stringS=READRSCS: (idé&) 





Reads the resource in a resource file specified by id& which must already be loaded. 


See LOADRSC&:. 


READRSCLONG&: 
Usage: long&=READRSCLONGE: (id&) 





Reads a 32-bit value from a resource file specified by the id& which must already be loaded. 
See LOADRSC&:. 


CHECKUID$: 
Usage: CHECKUIDS: (Uid1l&,Uid2&,Uid3é) 








Returns a string which is a unique product of the three supplied UIDs. 


SETPOINTERGRABON: 
Usage: SETPOINTERGRABON: (WinIdé, stateé) 








Enables (or disables) pointer grabs in a window. After this function has been called with stateé=1, 
any “down” event in this window will cause a pointer grab, terminated by the next corresponding “up” 
event. The terminating “up” event is also sent to the window with the grab. 
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This function would typically be used for “drag-and-drop”, and would typically be called after window 
creation so that pointer grab is enabled for the lifetime of the window. 


stateé&=0 disables the grab. 
See CLAIMPOINTERGRAB:. 


MACHINENAMES: 
Usage: nameS=MACHINENAMES : 














Returns the machine name. 


MACHINEUNIQUEID: 
Usage: MACHINEUNIQUEID: (BYREF high&,BYREF lowé&) 




















Sets highé and Lowé& (which are passed BYREF) to high and low parts of the machine's unique ID. 


ENDTASK&: 
Usage: ret &=ENDTASK&: (threadIdé, previousé) 





Sends a shutdown message to a window group in the thread, threadIdé. 


previousé specifies the window group in the thread that is previous to the one required. Hence, 
setting previous& to 0 will specify the first window group in the thread. 


The value returned by this procedure is the value of the window group on which action was taken, or -1 
if a window group following that specified by previousé was not present. This return value could be 
passed back to this procedure to end the next window group in the thread. 


An error will be raised if the window group is busy, does not respond to such requests or is in a system 
thread. 


See KILLTASK&:. 


KILLTASK&: 
Usage: ret &=KILLTASK&: (threadId&, previous&) 


Shuts down the window group that follows the window group specified by previous& in the thread, 
threadIdé. It will ignore any wishes of the window group not to be shutdown. 


The value returned by this procedure is the value of the window group on which action was taken, or -1 
if a window group following that specified by previous é was not present. This return value could be 
passed back to this procedure to end the next window group in the thread. 


See ENDTASK&:. 


GETTHREADIDFROMOPENDOC8: 
Usage: threadId&=GETTHREADIDFROMOPENDOC&: (doc$,BYREF previousé) 




















Returns the thread ID threadIdé& of the thread that contains the open document doc$. 


doc$ should contain the full path of the open document and could for example be 
c:\opl\prog.opo. 


previouss&, passed by reference, is useful for situations where the document may be open more than 
once. Setting previousé to zero will cause this procedure to find the first window group that 
contains doc$. If one is found, previousé will be set to the window group value of that found 
document. This value could then passed back to this procedure as previous6&, so the next window 
group instance of doc$ will be found, and so on. If this procedure sets previousé to -1 then doc$ 
could not be found after previous&. An error will also be raised if the open document is not found. 


GETTHREADIDFROMAPPUID8&: 
Usage: threadId&=GETTHREADIDFROMAPPUIDS&: (uid&,BYREF previousé) 
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Returns the thread ID threadIdé of the thread that contains a running instance of the application 
with UID vids. 


previous6&, passed by reference, is useful for situations where the application may be running more 
than once. Setting previousé to zero will cause this procedure to find the first window group that is 
an instance of this application. If one is found, previousé will be set to the value of that window 
group. This value could then passed back to this procedure as previous, so the next instance of the 
application can be found, and so on. If no instance of this application can be found following 
previousé then previousé will be set to -1. An error will also be raised if a running instance of 
the application is not found. 


SETFOREGROUND: 
Usage: SETFOREGROUND: 














Moves the calling process to foreground. 


See SETBACKGROUND:. 


SETBACKGROUND: 
Usage: SETBACKGROUND: 





Moves the calling process to background. 


See SETFOREGROUND:. 


SETFOREGROUNDBYTHREAD8&: 
Usage: ret &=SETFOREGROUNDBYTHREAD&: (threadId&,previousé&) 

















Moves the window group after previous& in the thread threadIdé to foreground. Using 
previous &=0 specifies the first window group in the thread. 


The value returned will be the window group on which action was taken, or -1 if the following window 
group was not found. This return value could be passed back to this procedure as previous6& to put 
the next window group in threadIdé to foreground. 


See SETBACKGROUNDBYTHREAD&:. 


SETBACKGROUNDBYTHREAD8&: 
Usage: ret &=SETBACKGROUNDBYTHREAD&: (threadId&,previousé&) 








Moves the window group after previousé in the thread threadIdé to background. Using 
previous &=0 specifies the first window group in the thread. 


The value returned will be the window group on which action was taken, or -1 if the following window 
group was not found. This return value could be passed back to this procedure again as a value for 
previousé to put the next window group in threadIdé to background. 


See SETFOREGROUNDBYTHREAD&:. 


GETNEXTWINDOWGROUPNAMES: 
Usage: name$=GETNEXTWINDOWGROUPNAMES: (threadIdé&,BYREF previous&) 




















Returns the name of the window group that follows the window group previousé in the thread 
threadIdé. If previous &=0 the procedure will return the name of the first window group found. 


See GETNEXTWINDOWID&:. 


GETNEXTWINDOWID8&: 
Usage: winId&=GETNEXTWINDOWID&: (threadIdé&,BYREF previous&) 

















Returns the ID of the window group that follows the window group previousé in the thread 
threadIdé. If previouss& is 0 the procedure will return the ID of the first window group found. 
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See GETNEXTWINDOWGROUPNAMES:. 


SENDKEYEVENTTOAPP8&: 


Usage: SENDKEYEVENTTOAPPé: (threadId&, previousé&, code&, scanCodeé, 
modifiersé&, repeatsé&) 




















Sends a key event to the window group (application) that follows the window group with ID 
previousé (or the first window group if previousé&=0), in the thread with ID threadIdé&. The 
key event is specified by code&, scanCode&, modifiersé& and repeatss&. 


The value returned is the window group to which the key was sent. 


IRDACONNECTTOSEND8&: 
Usage: IRDACONNECTTOSEND&: (protocolS,porté&) 














Synchronously sends out an infrared (IR) beam which looks for another infrared device. If another 
infrared device is looking to receive a beam then the devices will connect, otherwise this procedure will 
raise an error after a couple of seconds. 


protocolS can take either of the constants defined in System.oxh. These are KIrTinyTPS, used 
for communicating with other EPOC32 devices and KIrmuxS which is used for IR printing. 


The value 8 is recommended for port & when communicating with other EPOC32 devices. Both 
devices will need to be using the same value for port &. port & must be 2 for connecting to IR 
printers. 


If connecting to another EPOC32 device with this procedure the other device must connect by using 
IRDACONNECTTORECEIVE&:. 


After connecting to another EPOC32 device you can both send and receive information. 


After connecting to an IR printer use IRDAWRITE: to send text. When IRDADIASCONNECT: is 
called the printer will begin printing. 


See IRDACONNECTTORECEIVE:, IRDAWRITE:, IRDAREAD:, IRDADISCONNECT:, 
IRDAWAITFORDISCONNECT:. 


IRDACONNECTTORECEIVE: 
Usage: IRDACONNECTTORECEIVE: (protocolS,porté&,BYREF statusWé) 























Asynchronously waits, without timing-out, for another EPOC32 device to attempt to connect via 
infrared (IR). This procedure takes the status word statusWé&. When connection occurs the status 
word is set to zero. 


Both EPOC32 devices must be using the same port which is specified by port &. The recommended 
port is 8. 


One of the devices must connect with this procedure and the other with IRDACONNECTTOSEND&. 


protocolS specifies the IR protocol and should take the constant KIrTinyTPS, defined in 
System.oxh, when communicating with other EPOC32 devices. 


After connecting to another EPOC32 device you can both send and receive information. 


See IRDAWRITE:, IRDAREAD:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:. 


IRDAWRITE: 
Usage: IRDAWRITE: (chunk$, BYREF statusWé) 








Sends a string chunkS$ via infrared to another device after connection has been made. The procedure 
is asynchronous and the success of sending the string is reported in statusW&. 


See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDAREAD;, 
IRDADISCONNECT:, IRDAWAITFORDISCONNECT:. 
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IRDAREAD$: 
Usage: chunk$=IRDAREADS: 





Reads a text string via infrared from another device after connection has been made. The procedure is 
synchronous. 


See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDWRITE:, 
IRDADISCONNECT:, IRDAWAITFORDISCONNECT:. 


IRDAREADA: 
Usage: IRDAREADA: (stringAddré&, BYREF statusW&) 








Reads a text string via infrared from another device after connection has been made. The procedure is 
asynchronous with status word statusWs&. The string passed by address should have a maximum 
length of 255 bytes. To pass a string by address use, ADDR(string$). 


See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDWRITE:, 
IRDADISCONNECT:, IRDAWAITFORDISCONNECT:. 


IRDAWAITFORDISCONNECT: 
Usage: IRDAWAITFORDISCONNECT: 





Verifies, when disconnecting from another IR device, that the other device has received everything 
sent. It should therefore be called by the device that last sends some information. 


This procedure should not be used with printers: use IRDADISCONNECT: instead. 
See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDADISCONNECT:, 
IRDAWAITFORDISCONNECT:. 


IRDADISCONNECT: 
Usage: IRDADISCONNECT: 





Disconnects from another IR device. It should be called by the device that is the last to receive some 
information. IRDAWAITFORDISCONNECT: is used by the last device to send some information, 
except when printing via IR when IRDADISCONNECT: should be used to disconnect from the printer 
and commence printing. 


See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDADISCONNECT:, 
IRDAWAITFORDISCONNECT:. 


MAINBATTERYSTATUS&: 
Usage: MAINBATTERYSTATUS&: 





Returns the current power of the main batteries. The following possible return values are supplied as 
constants in System.oxh: 


CONST KBatteryZeroé& =0 
CONST KBatteryVeryLow& =1 
CONST KBatteryLowé& =2 

CONST KBatteryGoodé =3 
BACKUPBATTERYSTATUS&: 


Usage: BACKUPBATTERYSTATUSE&: 





Returns the current power of the backup batteries. The following possible return values are supplied as 
constants in System.oxh: 


CONST KBatteryZeroé& =0 


CONST KBatteryVeryLow& =1 
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CONST KBatteryLowé =2 


CONST KBatteryGoodé =3 


CAPTUREKEY8&: 





Usage: CAPTUREKEY&: (keyCodeé&,maské&,modifieré) 








Allows the program that calls it to capture keys when it is not in foreground. The keys to be captured 
are specified using keycode&, maské& and modifiers. The value returned is a handle which can be 





passed to CANCELCAPTUREKEY: to cancel the capture. 


The following constants are supplied in System.oxh to be used in conjunction with this procedure: 


CONST KModifierAutorepeatable&=&00000001 
CONST KModifierKeypad&=&00000002 

CONST KModifierLeftAlt&=&00000004 

CONST KModifierRightAl1t&=&00000008 

CONST KModifierAlt&=&00000010 

CONST KModifierLeftCtr1&=&00000020 

CONST KModifierRightCtrlé&=&00000040 
CONST KModifierCtrl1&=&00000080 

CONST KModifierLeftShift&=&00000100 
CONST KModifierRightShift&=&00000200 





CONST KModifierShift&=&00000400 


CONST KModifierLeftFuncé&=&00000800 





CONST KModifierRightFuncé=&00001000 


CONST KModifierFuncé&=&00002000 





CONST KModifierCapsLock&=&00004000 
CONST KModifierNumLock&=&00008000 
CONST KModifierScrollLock&=&00010000 
CONST KModifierKeyUpé&=&00020000 
CONST KModifierSpecial&=&00040000 


CONST KModifierDoubleClick&=&00080000 














CONST KModifierPureKeycode&=&00100000 











CONST KA11Modifiersé&=&001ffffEF 
See CANCELCAPTUREKEY®&:. 





CANCELCAPTUREKEY: 
Usage: CANCELCAPTUREKEY: (handleé) 

















Cancels an outstanding key capture which is specified by the handle handleé. 


See CAPTUREKEY®&:. 


SETPOINTERCAPTURE: 
Usage: SETPOINTERCAPTURE: (WinId&, flags&) 











Sets the (OPL) window with window ID winId& to capture pointer events. 
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flags& can take a summed combination of the following: 


value meaning 

0 capture disabled 

&01 capture enabled 

&02 capture (not drag-and-drop) 


When a window captures pointer events, the position of any events received will be relative to its 
origin, 1.e. the top left corner of that window, 1.e. the window’s 0,0 co-ordinate becomes the origin for 
pointer events. Events don’t need to be inside the window to be registered. For example, if the screen 
was touched | pixel above and | pixel to the left of a window that was capturing pointer events, the 
pointer event would be returned with the position of the event being -1,-1. 


“Capture (not drag-and-drop)” will cause events of the “drag-and-drop” nature to be sent to the window 
that would have received them had the pointer not been captured.. 


CLAIMPOINTERGRAB: 
Usage: CLAIMPOINTERGRAB: (WinIdé, stateé) 





Claims the pointer grab for the window with ID winIdé from another window, if a pointer grab is 
already in effect in the other window. All subsequent events will be delivered to this window, instead of 
the window that originally had the pointer grab. The next “up” event terminates the pointer grab, and is 
also delivered to the window that claimed the grab, if stateé is set to 1. 


This function would typically be used where clicking in a window pops up another window, and where 
the popped-up window wishes to grab the pointer as though the original click had been in that window. 


To summarise the values of state & for the OPL window, 


value meaning 


0 don't deliver the following “up” event to this window 
1 deliver the following “up” event to this window 
See SETPOINTERGRABON: 


OPENFILEDIALOGS$: 
Usage: fileS=OPENFILEDIALOGS: (seedFile$,uid1lé&,uid2&,uid3&) 

















Displays the standard ‘Open file’ dialog. seedFileS provides a starting file which is displayed when 
the dialog is opened. So, for example, if seedFile$=“C:\Documents\Myfile” then the file 
MyFile will be initially displayed in the ‘Name’ selector box, the Documents folder will be initially 
displayed in the ‘Folder’ selector box and C will be displayed in the disk selector. You must always 
seed the dialog: you cannot pass a null seedFileS string to OPENFILEDIALOGS:. If seedFile$ 
does not include a drive name, then an error is raised. 


The selection of files may be restricted by UID by specifying appropriate values for uid1&, uid2& 
and uid3é& in exactly the same way as when using the dFILE keyword. See the ‘Alphabetic Listing’ 
section for details of this. 


The return value is the filename, including the full path of the file selected to be opened. 


CREATEFILEDIALOGS$: 
Usage: file$=CREATEFILEDIALOGS: (seedPath$) 

















Displays the standard ‘Create new file’ dialog. seedPath$ provides a starting path which is 
displayed when the dialog is opened. So, for example, if seedPath$=“C:\Documents\” then the 
Documents folder will be intially displayed in the ‘Folder’ selector box and C in the disk selector. If 
you supply a filename in seedPath§, then this will be displayed as a suggested filename in the 
‘Name’ selector box. You must always seed the dialog: you cannot pass a null seedPathS string to 
CREATEFILEDIALOGS:. If seedPath$ does not include a drive name, then an error is raised. 
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The return value is the filename, including the full path of the file to be created. 


SAVEASFILEDIALOGS$: 
Usage: path$=SAVEASFILEDIALOGS: (seedPath$,BYREF useNewFileS) 

















Displays the standard ‘Save as’ dialog. seedPaths provides a starting path which is displayed when 
the dialog is opened. So, for example, if seedPath$=“C:\Documents\” then the Documents 
folder will be initially displayed in the ‘Folder’ selector box and C in the disk selector. If you supply a 
filename in seedPath§, then this will be displayed as a suggested filename in the ‘Name’ selector 
box. You must always seed the dialog: you cannot pass a null seedPath$ string to 
SAVEASFILEDIALOGS:. If seedPath$ does not include a drive name, then an error is raised. 


UseNewFile% specifies the initial setting of the checkbox which determines whether a new file 
should be used when saving. This value is non-zero then the tick will be set initially, if it is zero, then it 
will not be. The procedure writes back a value to this variable which will be KTrue% if the symbol is 
set on exiting the dialog and KFalses% if not (see the listing of Const.oph in Appendix E for 
definitions of these constants). If you pass #0 as the value of this argument, then this item will not be 
displayed in the dialog at all (as in many Series 5 applications) so that whether a new file is used on not 
is not decided by the user, but by the programmer. 


The return value is the filename to save as, including the full path. 


Sprite AND Bitmap OPX 


In general sprite procedures behave in a similar way to the sprite keywords of the Series 3a, 3c and 
Siena. 


To use this OPX, you must included the header file Bmp.oxh, which contains the following declaration: 





DECLARE OPX BMP, &10000258,5100 











BITMAPLOADS&: (name$,index&) : 1 


BITMAPUNLOAD: (id&) : 2 











BITMAPDISPLAYMODE&: (id&) : 3 





SPRITECREATE&: (winIld%,xé&,y&,flags&) : 4 











SPRITEAPPEND: (time&,bitmap&,maskBitmapé&, invertMaské,dxé&,dy&) : 5 














SPRITECHANGE: (indexé&, timeé,bitmap&,maskBitmapé&, invertMaské&,dxé, 
dy&) : 6 





PRITEDRAW: () : 7 








S 
SPRITEPOS: (x&,y&) : 8 
S 


PRITEDELETE: (id&) : 9 























SPRITEUSE: (id&) : 10 














END DECLARE 











BITMAPLOAD8&: 
Usage: id&=BITMAPLOAD&: (name$, index&) 


Loads a bitmap from the file name$ (in the current directory if no other is specified). If the file 
contains more than one bitmap, then indexé specifies which bitmap to load. The first (or only) 
bitmap is specified by indexé having the value 0. The value returned is the ID of the open bitmap, 
which may be used to refer to it when calling sprite procedures or when using gBUTTON, for example. 


See BITMAPUNLOAD:. 


BITMAPUNLOAD: 
Usage: BITMAPUNLOAD: (id&) 
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Unloads the bitmap whose ID is idé&. You can call BITMAPUNLOAD: immediately after passing the 
bitmap ID to gBUTTON or, if used with the Sprite OPX procedures, after drawing the sprite, as the 
access count on a bitmap is incremented to ensure it is not unloaded prematurely. 


See BITMAPLOAD&:. 


BITMAPDISPLAYMODE&: 
Usage: mode &=BITMAPDISPLAYMODE&: (id&) 





Returns the graphics mode of the bitmap with ID id&. The graphics mode is that specified at its 
creation (see gCREATEBIT), i.e. 0 for 2-colour mode, | for 4-colour mode and 2 for 16-colour mode. 


SPRITECREATE&: 
Usage: id&é=SPRITECREATES&: (winIld%,xé&,yé&,flags&) 

















Initialises a sprite in the window given by winId% with its top left-hand corner at x&, y&. The value 
of flagsé& determines whether or not the sprite’s members are flashing. If (flags& AND 1)=1 
then they are flashing and if the value is 0 then they are not. The value returned is the ID of the sprite 
which should be used when referring to it in other sprite procedures. 


See SPRITEAPPEND:, SPRITECHANGE:, SPRITEDRAW:, SPRITEPOS:, SPRITEDELETE:, 
SPRITEUSE:. 


SPRITEAPPEND: 
Usage: SPRITEAPPEND: (time&,bitmapé,maskBitmapé, invertMaské, dxé,dy&) 














Appends members or frames to the current sprite, which must have been created using 
CREATESPRITE&: before attempting to append to it. bitmaps is the ID of the bitmap to be used for 
this member of the sprite, and maskBitmapé is the ID of the bitmap to be used as a mask. The 
bitmap and mask must be of identical sizes. invertMaské takes the value of | or 0 to determine 
whether the mask is to be inverted or not respectively. For example, if you are using identical bitmap 
and mask and invertMaské&=1 then the member will appear as the bitmap, whereas if 
invertMaské&=0, the member will be blank. time& is the period of time in microseconds for which 
the member appears in the sprite and dx&, dyé is the offset position of the top left-hand of the bitmap 
from the top left-hand corner of the sprite. 


See SPRITECHANGE:. 


SPRITECHANGE: 
Usage: SPRITECHANGE: (id&,timeé&,bitmapé&,maskBitmapé, invertMaské,dx&,dyé&) 














Changes a member of a sprite originally set up with SPRITEAPPEND. 


idé specifies the number of the sprite member which is to be changed. This number is determined by 
the order in which the members were originally appended, the first member to be appended being 
labelled 0. bitmapé is the ID of the bitmap to be used for this member of the sprite, and 
maskBitmap6& is the ID of the bitmap to be used as a mask. The bitmap and mask must be of 
identical sizes. invertMaské takes the value of 1 or 0 to determine whether the mask is to be 
inverted or not respectively. For example, if you are using identical bitmap and mask and 
invertMaské&=1 then the member will appear as the bitmap, whereas if invertMask&=0, the 
member will be blank. timeé is the period of time in microseconds for which the member appears in 
the sprite and dx&, dyé& is the offset position of the top left-hand of the bitmap from the top left-hand 
corner of the sprite. 


A sprite may not be changed unless it has already been drawn. 


See SPRITEAPPEND:, SPRITEDRAW:. 


SPRITEDRAW: 
Usage: SPRITEDRAW: 
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Draws the sprite once it has been set up. It need only be called once, and any changes made to the 
sprite are made as soon as the procedure making the change is called. The sprite will be drawn in the 
window and at the position specified by the arguments passed to SPRITECREATE. 


See SPRITECREATE&:, SPRITEAPPEND:, SPRITECHANGE:, SPRITEPOS:. 


SPRITEPOS: 
Usage: SPRITEPOS: (x&, y&) 





Repositions the whole of the current sprite to the point x&, y&. 


See SPRITECREATE&:,SPRITEDRAW:. 


SPRITEDELETE: 
Usage: SPRITEDELETE: (id&) 




















Deletes the sprite with ID idé. 


SPRITEUSE: 
Usage: SPRITEUSE: (id&) 














Sets the current sprite to be that with ID idé in order that it may be changed. 
See SPRITECHANGE:, SPRITEPOS:. 


aN Note that using many sprites at one time may cause undesirable effects. Firstly, sprites maybe 
animated at a slower speed than requested, and secondly the response time to any key or pointer 
event can be lengthened considerably. The number of sprites which can be drawn at one time 
without these effects occurring depends mainly on the animation speed: the faster it is the less 
sprites may be used successfully at one time. As a general rule, it is advisable not to use more than 
around 20 sprites at any one time when the animation speed is 0.2 sec, but you should experiment 
to find out what is suitable for your particular program. 


DaTaBAsE OPX 


To use this OPX, you must included the header file Dbase.oxh, which contains the following 
declaration: 





DECLARE OPX DBASE, KUidOpxDBaseé&, KOpxDBaseVersion% 




















DbAddField: (keyPtr&,fieldNameS,orderé&) : 1 





DbAddFieldTrunc: (keyPtré, fieldNameS$,order&,trunc&) : 2 





DboCreateIndex: (index$,keyPtré,dbase$,table$) : 3 
DoDeleteKey: (keyPtr&) : 4 

DoDropIndex: (index$,dbase$,table$) : 5 
DoGetFieldCounté&: (dbase$,tableS) : 6 
DoGetFieldNameS: (dbase$,table$,fieldNumé&) : 7 
DbGetFieldTypeé&: (dbase$,tableS,fieldNumé) : 8 
DbIsDamagedé: (dbase$) : 9 


DbIsUniqueé: (keyPtr&) : 10 





DobMakeUnique: (keyPtr&) : 11 
DbNewKey&: : 12 


DbRecover: (dbase$) : 13 





DobSetComparison: (KeyPtr&,comp&) : 14 
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END DECLARE 











DBADDFIELD: 
Usage: DBADDFIELD: (key&, field$,orderé) 


Adds the field, fieldS, to the key, key& (see DBNEWKEY«&: for creating a new key). This new key 
can then be used to create an index on a table. order & specifies how this field should be ordered: 








value meaning constant declaration in Dbase.oxh 
1 ascending CONST KDbAscending&=1 
0 descending CONST KDbDescending&=1 


You can use this procedure repeatedly to add more than one field to the same key. The order in which 
the fields are added dictates the significance of these fields in building up the index. The first field 
added to a key is the primary field; if there were any identical values in this field then the secondary 
field would be used and so on. For example, if the primary field in an ‘Address’ table was ‘Surname’ 
and there were two people with the surname Brown, then the secondary field or tertiary fields like 
‘Forename’ and ‘Age’ might be used to define how the index will be ordered. 


When using string fields in an index they cannot be longer than 240 bytes. To limit the size of a string 
field see CREATE in the ‘Alphabetic Listing’ chapter. If a string field is the last field in a key (or first 
and only) then it may be truncated to a specified length - see DBADDFIELDTRUNC:. 


aN Note that the size of an index can become huge if the key is long. The key length & is the length in 
bytes of the sum of all the fields in the key. An integer or a long integer field is 4 bytes, a 
floating-point field 8 pyc and a text field depends on the length assigned to it (see also the 
pe a The size of the index depends at least linearly on k and hence may be large if 
the key 1s long. 


When the key has been built as required, it can be used to create an index. 


See DBCREATEINDEX:. 


DBADDFIELDTRUNC: 
Usage: DBADDFIELDTRUNC: (keyé, field$,orderé&,truncé) 





Adds a truncated string field field$ to the key key&. Only the last field added to a key (or first and 
only) can be truncated. order& specifies how this field should be ordered and may take the values: 


value meaning constant declaration in Dbase.oxh 
1 ascending CONST KDbAscending&=1 
0 descending CONST KDbDescendingé&=1 


truncé is the truncation length and determines how many bytes of the string field will be used in 
building up the index (up to 240). 


This procedure is useful for building up indexes on OPL16 databases whose string fields have a set 
length of 255 bytes. When the key has been built up as required it can be used to create an index. 


See DBADDFIELD:, DBCREATEINDEX:. 


DBCREATEINDEX: 
Usage: DBCREATEINDEX: (indexS, key&, fileS,table$) 

















Creates an index with the name indexS on the table table$S in the database fileS. The index is 
used for sorting and vastly increases the speed in table lookup. The index is based on keys, the 
supplied key. The database must be closed when this procedure is used. 


The opening of an ordered view on a table must be requested in the SQL query in the OPEN command. 
See Appendix F for SQL specification. If a suitable index has been created then it will be used. 


See DBNEWKEY:, DBADDFIELD:, DBADDFIELDTRUNC:, DBMAKEUNIQUE:, 
DBSETCOMPARISON:, DBDROPINDEX:, OPEN. 
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DBDELETEKEY: 
Usage: DBDELETEKEY: (key&) 




















Deletes the key keyé&. This should be called as soon as the key is no longer required. Any keys left 
undeleted when all modules that declare or include a declaration of the Dbase OPX have been unloaded 
will be automatically deleted 


See DBNEWKEY&. 


DBDROPINDEX: 
Usage: DBDROPINDEX: (index$, fileS,tableS) 





Drops the index index$ of the table table$ of the database file$. The database must be closed to 
use this procedure. 


See DBCREATEINDEX:. 


DBGETFIELDCOUNTS8: 
Usage: n&=DBGETFIELDCOUNTS: (dbase$,table$) 














Returns the number of fields in one of the records in the table table$ of the database dbase$. This 
number can then be used to analyse the contents of the record. 


See DBGETFIELDNAME$:, DBGETFIELDTY PE&:. 


DBGETFIELDNAMES$: 
Usage: name$=DBGETFIELDNAMES: (dbase$,tableS$, fieldNumé) 

















Returns the name of the field whose number is fie1dNumé in the table table$ of the database 
dbaseS. This is useful for analysing the records of a table. 


See DBGETFIELDCOUNT&:, DBGETFIELDTY PE&:. 


DBGETFIELDTYPE&: 
Usage: type&=DBGETFIELDTYPE&: (dbase$,tableS, fieldNumé) 

















Returns the type of the field whose number is f£ieldNumé in the table table$ of the database 
dbaseS. This is useful for analysing the records of a table. 


The values that me be returned (many of which aren’t supported by OPL databases), are as follows: 
value type 

0 bit 

1 signed byte (8 bits) 


ee 


unsigned byte (8 bits) 

integer (16 bits) 

unsigned integer (16 bits) 

long integer (32 bits) 

unsigned long integer (32 bits) 

64-bit integer 

single precision floating-point number (32 bits) 


double precision floating-point number (64 bits) 


oO wWmnanNnn nan fF W WN 


date/time object 


ASCII text 


= 
Oo 
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11 Unicode text 


12 Binary 

13 LongText8 
14 LongText16 
15 LongBinary 


Types 2,4,8,10 correspond to OPL’s 3%,&, floating point and $ types respectively. 
See DBGETFIELDCOUNT&, DBGETFIELDNAME& 


DBISDAMAGED8&: 
Usage: i&=DbIsDamagedé: (dbase$) 


Returns | if the database dbase$ considers that it may have damaged indexes and 0 if not. If the 
database is damaged, then this does not make it unusable, but attempting to use any damaged index will 
result in an error. Recovering the database will restore any damaged indexes. 


See DBRECOVER:. 


DBISUNIQUE8&: 
Usage: i&=DBISUNIQUES: (key&) 





Returns -1 if the key key& is unique or 0 if it is not. 
See DBMAKEUNIQUE:. 


DBMAKEUNIQUE: 
Usage: DBMAKEUNIQUE: (keyé&) 














Sets the key key& to be unique. The index created will then not allow any records to be added if they 
exactly match the indexed fields of another record. 


See DBNEWKEY:, DBADDFIELD:, DBCREATEINDEX:. 


DBNEWKEY8&: 
Usage: k&=NEWKEY&: 














Returns a handle to a key which can be used for creating indexes. 


See DBDELETEKEY:, DBCREATEINDEX:, DBADDFIELD:, DBADDFIELDTRUNC:. 


DBRECOVER: 
Usage: DBRECOVER: (dbase$) 














Recovers a damaged database dbaseS, restoring any damaged indices. 


See DBISDAMAGED&:. 


DBSETCOMPARISON: 
Usage: DBSETCOMPARISON: (keyé, compé) 





The text comparison is used to determine the order of an index. The argument comps sets the text 
comparison mode of a key key&, and takes one of the constant values supplied in the header file 
Dbase.oxh: 


CONST KDbCompareNormal & =0 
CONST KDbCompareFolded &=1 


CONST KDbCompareCollatedé =2 
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PRINTER OPX 


Printer OPX provides access to print and text handling. An object to be printed is first created 


dynamically by sending text, bitmaps 


and formatting information. Printing itself is then handled by 


calling standard print dialogs. One procedure is provided for each of the four dialogs usually called 


from standard applications. 





DECLARE 














Sends 
Inser 
SendNewParaToPrinter: 


InsertNewPara: (pos&) 


OPX PRINTER, KUidOpxPrinteré, KOpxPrinterVersion% 
tringToPrinter: (string$S) : 1 


tString: (string$,pos&) : 2 


3 
4 


SendSpecialCharToPrinter: (character%S) : 5 








InsertSpecialChar: 


(character%S,pos&) : 6 


SetAlignment: (alignment%) : 7 


InitialiseParaFo 
RightMarginInTwipsé, 
VerticalAlignment%, 
SpaceBeforeInTwipsé, 
KeepWithNext%, S 
BorderMarginInTwipsé, 








SetLocalParaFormat: : 9 


SetGlobalParaFormat: 


RemoveSpecificParaFo 


SetFontName: (name$) : 1 


SetFontHeight: (heigh 


SetFontPosition: (pos%) 


SetFontWeight: (weight%) 





SetFontPosture: (posture 


SetFontStrikethrough: (s 











SetFontUnderlin 


rmat: (Red&, 
IndentInTwipsé, 
LineSpacingInTwipsé&, 
SpaceAfterInTwipsé, 
tartNewPageS, 
DefaultTabWidthInTwipsé) : 8 


Green&, Blue&, LeftMarginInTwipsé, 

HorizontalAlignment%, 
LineSpacingControl%, 
KeepTogetherS, 


WidowOrphan%S, Wrap%, 


10 


%) 


16 


trikethrough’) 17 


fo) 


18 





: (underlines) 





SetGlobalCha 


RemoveSpecificCharFormat: 





SendBitmapTo 


Printe 


rFormat: 


19 
20 


r: (bitmapHandles&) 21 


Inse 


Send 


InsertScaledBitmap: (bitmapHandleé,posé, xScaleé, yScaleé&) 


Prin 
Send 


Rese 





Prin 


PageSetupDialog: 


rtBitmap: (bitmapHandles&, posé&) 22 








ScaledBitmapTo 





terDocLength&: 25 
RichTextToPrinter: (richTextAddress&) 
tPrinting: 27 


28 





tPreviewDialog: 29 
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Printer: (bitmapHandle&,xScaleé&, yScaleé) 


23 
24 


26 


PrintRangeDialog: : 30 
PrintDialog: : 31 


SendBufferToPrinter: (Addr&) : 32 








END DECLARE 











SENDSTRINGTOPRINTER: 
Usage: SENDSTRINGTOPRINTER: (string$) 








Append a string to whatever has already been sent to the printer. 


See INSERTSTRING:, SENDNEWPARATOPRINTER:. 


INSERTSTRING: 
Usage: INSERTSTRING: (string$,pos&) 





Insert string$S at position posé& in the buffer. Inserting at position zero puts the string ahead of 
anything already sent or inserted. 


See SENDSTRINGTOPRINTER:, INSERTNEWPARA:. 


SENDNEWPARATOPRINTER: 
Usage: SENDNEWPARATOPRINTER: 

















Paragraphs delimit paragraph formatting, such as centring. This procedure is equivalent to 














SENDSPECIALCHARTOPRINTER: (KParagraphDelimiters) . 


See SENDSPECIALCHARTOPRINTER:, INSERTNEWPARA:, SENDSTRINGTOPRINTER:. 





INSERTNEWPARA: 
Usage: INSERTNEWPARA: (posé) 














Inserts a new paragraph at position posé& in the buffer. 


See SENDNEWPARATOPRINTER;:, INSERTSTRING:. 


SENDSPECIALCHARTOPRINTER: 
Usage: SENDS PECIALCHARTOPRINTER: (character$) 

















Sends a special character, for example line and page breaks etc., to the printer. Constants for special 
characters are defined in Const.oph (see the ‘Calling Procedures’ chapter for details of how to use this 
file and Appendix E for a listing of it) as follows: 


CONST KParagraphDelimiter%S=S$06 
CONST KLineBreak%=$07 

CONST KPageBreak%=S$08 

CONST KTabCharacter%=S09 

CONST KNonBreakingTab%=S0a 
CONST KNonBreakingHyphen%=$0b 


CONST KPotentialHyphen%=S0c 





CONST KNonBreakingSpace%=$10 











CONST KVisibleSpaceCharacter%=S0f 
See SENDNEWPARATOPRINTER:, INSERTSPECIALCHAR:. 
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INSERTSPECIALCHAR: 
Usage: INSERTSPECIALCHAR: (character%,posé) 














Inserts a special character at pos & in the buffer. 


See SENDSPECIALCHARTOPRINTER:. 


SETALIGNMENT: 
Usage: SETALIGNMENT: (alignment’) 











Sets alignment state of a paragraph. Default is KPrintLeftAligns. 


The setting does not take effect until either SETLOCALPARAFORMAT: or 
SETGLOBALPARAFORMAT: is called. The allowable alignments, defined in Printer.oxh, are: 





CONST KPrintLeftAlign% = 0 
CONST KPrintCenterAligns = 1 
CONST KPrintRightAligns = 2 
CONST KPrintJustifiedAligns = 3 
CONST KPrintUnspecifiedAligns = 4 
See INITIALISEPARAFORMAT.:. 


INITIALISEPARAFORMAT: 


Usage: INITIALISEPARAFORMAT: (Red%, Greens, Blue%, LeftMarginInTwipsé, 
RightMarginInTwips&, IndentInTwips&, 
HorizontalAlignment%S, VerticalAlignment%, 
LineSpacingInTwips&, LineSpacingControl%, 
SpaceBeforeInTwipsé&, SpaceAfterInTwipsé&, 
KeepTogether%S, KeepWithNext%, 
StartNewPage%, WidowOrphan%, Wrap%, 
BorderMarginInTwipsé&, 
DefaultTabWidthInTwipsé) 














Sets a state for formatting. The setting does not take effect until either SETLOCALPARAFORMAT or 
SETGLOBALPARAFORMAT is called. 








Reds, Green%,Blue% set the background colour. Each value can be in the range 0 to 255. Default 
colour is white, with all three arguments equal to 255. 


LeftMarginInTwipssé sets left text margin relative to left page margin. Default is zero. 
RightMarginInTwipsé sets right text margin, relative to right page margin. Default is zero. 


IndentInTwipssé sets left, right and first line indent. Default is zero. 





HorizontalAlignment% sets horizontal alignment of paragraph. Default is left alignment. See 
SETALIGNMENT for values. 











VerticalAlignment% sets vertical alignment of paragraph (for use by spreadsheet applications). 
Default is top alignment. Allowable values, supplied in Printer.oxh, are: 


CONST KPrintTopAligns = 0 


CONST KPrintBottomAlign%s = 2 





CONST KPrintUnspecifiedAlign%s = 4 
LineSpacingInTwipss sets inter-line spacing in twips. Default is 200 (10 point). 


LineSpacingContro1% sets the control for LineSpacingInTwipsé value. Default is 
KLineSpacingAtLeastInTwipsé. Allowable values are 





CONST KLineSpacingAtLeastInTwips% = 0 
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CONST KLineSpacingExactlyInTwips%S = 1 





SpaceBeforeInTwipsé sets the space above a paragraph. Default is zero. 
SpaceAfterInTwipss sets the space below a paragraph. Default is zero. 


KeepTogether% prevents a page break within paragraph when KTrue®. Default is KFalses%. 
(Constants are defined in Const.oph.) 


KeepWithNext% prevents a page break between this paragraph and the following paragraph when 
KTrue®%. Default is KFalse%. 


StartNewPage% inserts a page break immediately before this paragraph when KTrue%. Default is 
KFalse%. 





WidowOrphan$ prevents the printing of the last line of a paragraph by itself on the top of a new page 
(widow) or the first line of a paragraph by itself on the bottom of the page (orphan). Default is 
KFalses. 


Wrap forces the paragraph to line wrap at the right margin when KTrue%. KFalse% disables line 
wrap. Default is KTrueS. 


BorderMarginInTwipss sets distance in twips between paragraph border and enclosed text (must 
be non-negative). Default is zero. 


DefaultTabWidthInTwipsé specifies the spacing between the default tab stops. Default is 360. 


SETLOCALPARAFORMAT: 
Usage: SETLOCALPARAFORMAT: 





Sets the initialised global paragraph formatting as local. 


See SETGLOBALPARAFORMAT.:. 


SETGLOBALPARAFORMAT: 
Usage: SETGLOBALPARAFORMAT : 





Sets the local paragraph format as global (after initialising formatting). 


See SETLOCALPARAFORMAT:, REMOVESPECIFICPARAFORMAT:. 


REMOVESPECIFICPARAFORMAT: 
Usage: REMOVES PECIFICPARAFORMAT: 

















Unsets local paragraph formatting, using global formatting instead 


See SETGLOBALPARAFORMAT:, SETLOCALPARAFORMAT:. 


SETFONTNAME: 
Usage: SETFONTNAME: (name$) 








Gives a new font name. Takes immediate effect locally, but requires the use of 
SETGLOBALCHARFORMAT: to set as the global default. 


SETFONTHEIGHT: 
Usage: SETFONTHEIGHT: (height3) 











Gives a new font height in twips 
(1 twip = 1/20 points or 1/1440 inches) 


Takes immediate effect locally, but requires the use of SETGLOBALCHARFORMAT: to set as the 
global default. 
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SETFONTPOSITION: 
Usage: SETFONTPOSITION: (POS%) 


Sets font position as normal, superscript or subscript. The following constants can be used for this: 
CONST KPrintPosNormals = 0 


CONST KPrintPosSuperscripts = 1 








CONST KPrintPosSubscript%s = 2 


Takes immediate effect locally, but requires the use of SETGLOBALCHARFORMAT: to set as the 
global default. 


SETFONTWEIGHT: 
Usage: SETFONTWEIGHT: (weight3) 








Sets the font weight (normal or bold). Allowable values are: 


CONST KStrokeWeightNormal%s = 0 





CONST KStrokeWeightBolds = 1 


Takes immediate effect locally, but requires the use of SETGLOBALCHARFORMAT: to set as the 
global default. 


SETFONTPOSTURE: 
Usage: SETFONTPOSTURE: (posture%) 





Sets font posture using the following constants: 


CONST KPostureUpright%S = 0 





CONST KPosturelItalics = 1 
Takes immediate effect locally, but requires the use of SETGLOBALCHARFORMAT: to set as the 
global default. 


SETFONTSTRIKETHROUGH: 
Usage: SETFONTSTRIKETHROUGH: (strikethrough%) 


Set strike-through on or off using: 


CONST KStrikethroughOff%s = 0 








CONST KStrikethroughOns = 1 


Takes immediate effect locally, but requires the use of SETGLOBALCHARFORMAT: to set as the 
global default. 


SETFONTUNDERLINE: 
Usage: SETFONTUNDERLINE: (underline) 














Set underline on or off using: 


CONST KUnderlineOff% = 0 





CONST KUnderlineOn%s = 1 


Takes immediate effect locally, but requires the use of SETGLOBALCHARFORMAT: to set as the 
global default. 


SETGLOBALCHARFORMAT: 
Usage: SETGLOBALCHARFORMAT: 





Sets the currently active character format to be the global default. 
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See REMOVESPECIFICCHARFORMAT.:. 


REMOVESPECIFICCHARFORMAT: 
Usage: REMOVES PECIFICCHARFORMAT: 

















Unsets local character formatting, replacing it with the global formatting instead. 


See SETGLOBALCHARFORMAT.:. 


SENDBITMAPTOPRINTER: 
Usage: SENDBITMAPTOPRINTER: (bitmapHandleé) 








Appends a bitmap from its handle bitmapHandlesé. 
See INSERTBITMAP:, SENDSCALEDBITMAPTOPRINTER:. 


INSERTBITMAP: 
Usage: INSERTBITMAP: (bitmapHandleé,pos&) 





Inserts a bitmap specified by bitmapHand1leé at position posé in the buffer to be sent to the printer. 
The handle is the same as that returned by gLOADBIT. 


See SENDBITMAPTOPRINTER:, INSERTSCALEDBITMAP.:. 


SENDSCALEDBITMAPTOPRINTER: 
Usage: SENDSCALEDBITMAPTOPRINTER: (bitmapHandleé, xScaleé, yScale&) 














Appends a scaled bitmap specified by bitmapHand1leé and scaled according to xScaleé& and 
yScaleé to the buffer sent to the printer. The handle is the same as that returned by gLOADBIT. 
Default scaling is xScale& = yScaleé& = 1000. 


See SENDBITMAPTOPRINTER:, INSERTSCALEDBITMAP.:. 


INSERTSCALEDBITMAP: 
Usage: INSERTSCALEDBITMAP: (bitmapHandleé,pos&,xScaleé, yScaleé) 











Inserts a scaled bitmap specified by bitmapHand1leé and scaled according to xScaleé and 
yScaleé at position posé in the buffer sent to the printer. The handle is the same as that returned by 
gLOADBIT. 


See INSERTBITMAP:, SENDSCALEDBITMAPTOPRINTER:. 


PRINTERDOCLENGTH&: 
Usage: PRINTERDOCLENGTHE: 














Returns the count of characters currently held in the buffer. It is not possible to insert characters beyond 
the length of the document buffer. Bitmaps and special characters each count as one character. 


SENDRICHTEXTTOPRINTER: 
Usage: SENDRICHTEXTTOPRINTER: (richTextAddressé&) 











Sends the address of a rich text object richTextAddress& to the printer. This is intended to be 
used on a pointer returned by another OPX. This new Rich Text will replace all content currently 
stored. 


RESETPRINTING: 
Usage: RESETPRINTING: 














Deletes all text, bitmaps and formatting in the printing buffer. 
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PAGESETUPDIALOG: 
Usage: PAGESETUPDIALOG: 














Calls the standard page setup dialog. 
See PRINTPREVIEWDIALOG:, PRINTRANGEDIALOG:, PRINTDIALOG:. 


PRINTPREVIEWDIALOG: 
Usage: PRINTPREVIEWDIALOG: 














Calls the standard print preview dialog. This allows the data sent to the printer to be viewed. The other 
three dialogs can all be called from this dialog. 


See PAGESETUPDIALOG:, PRINTRANGEDIALOG:, PRINTDIALOG:. 


PRINTRANGEDIALOG: 
Usage: PRINTRANGEDIALOG: 





Calls a standard print range dialog. 


See PAGESETUPDIALOG:, PRINTPREVIEWDIALOG:, PRINTDIALOG:. 


PRINTDIALOG: 
Usage: PRINTDIALOG: 


Calls a standard print dialog. 
See PAGESETUPDIALOG:, PRINTPREVIEWDIALOG:, PRINTRANGEDIALOG:. 


SENDBUFFERTOPRINTER: 
Usage: SENDBUFFERTOPRINTER: (addr&) 














Appends the contents of a buffer to whatever has already been sent to the printer. The addr& 
parameter should be the address of a buffer into which text has been inserted by dEDITMULTI. 
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